<html>
<META http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<head>
<title>Section 5.5.&nbsp; Opening a Stream</title>
<link rel="STYLESHEET" type="text/css" href="images/style.css">
<link rel="STYLESHEET" type="text/css" href="images/docsafari.css">
</head>
<body>
<table width="100%" border="0" cellspacing="0" cellpadding="0">
<tr><td><div STYLE="MARGIN-LEFT: 0.15in;"><a href="toc.html"><img src="images/team.gif" width="60" height="17" border="0" align="absmiddle"  alt="Team BBL"></a></div></td>
<td align="right"><div STYLE="MARGIN-LEFT: 0.15in;">
<a href=ch05lev1sec4.html><img src="images/prev.gif" width="60" height="17" border="0" align="absmiddle" alt="Previous Page"></a>
<a href=ch05lev1sec6.html><img src="images/next.gif" width="60" height="17" border="0" align="absmiddle" alt="Next Page"></a>
</div></td></tr></table>
<br><table width="100%" border="0" cellspacing="0" cellpadding="0"><tr><td valign="top"><a name="ch05lev1sec5"></a>
<h3 class="docSection1Title">5.5. Opening a Stream</h3>
<p class="docText"><a name="idd1e35858"></a><a name="idd1e35863"></a><a name="idd1e35868"></a><a name="idd1e35873"></a><a name="idd1e35878"></a><a name="idd1e35883"></a><a name="idd1e35888"></a><a name="idd1e35895"></a><a name="idd1e35900"></a><a name="idd1e35907"></a><a name="idd1e35912"></a><a name="idd1e35919"></a><a name="idd1e35924"></a><a name="idd1e35929"></a><a name="idd1e35934"></a><a name="idd1e35939"></a>The following three functions open a standard I/O stream.</P>
<a name="inta56"></a><P><table cellspacing="0" class="allBorders" border="1" RULES="none" cellpadding="5"><colgroup><col width="550"></colgroup><thead></thead><tr><TD class="docTableCell" align="left" valign="top"><p class="docText">
<a name="PLID0"></a><div class="v1"><a href="ch05lev1sec5.html#PLID0">[View full width]</a></div><pre>
#include &lt;stdio.h&gt;

FILE *fopen(const char *restrict <span class="docEmphItalicAlt">pathname</span>, const
<img border="0" width="14" height="9" alt="" align="left" src="images/ccc.gif"> char *restrict <span class="docEmphItalicAlt">type</span>);

FILE *freopen(const char *restrict <span class="docEmphItalicAlt">pathname</span>, const
<img border="0" width="14" height="9" alt="" align="left" src="images/ccc.gif"> char *restrict <span class="docEmphItalicAlt">type</span>,
              FILE *restrict <span class="docEmphItalicAlt">fp</span>);

FILE *fdopen(int <span class="docEmphItalicAlt">filedes</span>, const char *<span class="docEmphItalicAlt">type</span>);
</pre><BR>

</P></td></TR><TR><TD class="docTableCell" align="right" valign="top"><p class="docText">All three return: file pointer if OK, <tt>NULL</tt> on error</p></TD></tr></table></P><BR>
<p class="docText">The differences in these three functions are as follows.</P>
<div style="font-weight:bold"><ol class="docList" type="1"><li><div style="font-weight:normal"><p class="docList">The <tt>fopen</tt> function opens a specified file.</P></div></LI><li><div style="font-weight:normal"><p class="docList">The <tt>freopen</tt> function opens a specified file on a specified stream, closing the stream first if it is already open. If the stream previously had an orientation, <tt>freopen</tt> clears it. This function is typically used to open a specified file as one of the predefined streams: standard input, standard output, or standard error.</P></div></LI><li><div style="font-weight:normal"><p class="docList">The <tt>fdopen</tt> function takes an existing file descriptor, which we could obtain from the <tt>open</tt>, <tt>dup</tt>, <tt>dup2</tt>, <tt>fcntl</tt>, <tt>pipe</tt>, <tt>socket</tt>, <tt>socketpair</tt>, or <tt>accept</tt> functions, and associates a standard I/O stream with the descriptor. This function is often used with descriptors that are returned by the functions that create pipes and network communication channels. Because these special types of files cannot be opened with the standard I/O <tt>fopen</tt> function, we have to call the device-specific function to obtain a file descriptor, and then associate this descriptor with a standard I/O stream using <tt>fdopen</tt>.</p><blockquote><p><p class="docList">Both <tt>fopen</tt> and <tt>freopen</tt> are part of ISO C; <tt>fdopen</tt> is part of POSIX.1, since ISO C doesn't deal with file descriptors.</p></P></blockquote></div></li></ol></div>
<p class="docText">ISO C specifies 15 values for the <span class="docEmphasis">type</span> argument, shown in <a class="docLink" href="#ch05fig02">Figure 5.2</a>.</P>
<a name="ch05fig02"></a><p><table cellspacing="0" class="allBorders" border="1" RULES="groups" cellpadding="5"><caption><H5 class="docTableTitle">Figure 5.2. The <span class="docEmphasis">type</span> argument for opening a standard I/O stream</h5></caption><colgroup><col width="125"><col width="400"></colgroup><thead><tr><th class="rightBorder bottomBorder thead" scope="col" align="center" valign="top"><p class="docText"><span class="docEmphRoman"><span class="docEmphasis">type</span></span></p></th><th class="bottomBorder thead" scope="col" align="center" valign="top"><p class="docText"><span class="docEmphRoman">Description</span></p></th></tr></thead><tr><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>r</tt> or <tt>rb</tt></p></td><td class="docTableCell" align="left" valign="top"><p class="docText">open for reading</p></td></tr><tr><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>w</tt> or <tt>wb</tt></p></td><TD class="docTableCell" align="left" valign="top"><p class="docText">truncate to 0 length or create for writing</P></td></TR><TR><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>a</tt> or <tt>ab</tt></p></TD><TD class="docTableCell" align="left" valign="top"><p class="docText">append; open for writing at end of file, or create for writing</P></td></TR><tr><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>r+</tt> or <tt>r+b</tt> or <tt>rb+</tt></P></TD><td class="docTableCell" align="left" valign="top"><p class="docText">open for reading and writing</P></TD></tr><TR><TD class="rightBorder" align="left" valign="top"><p class="docText"><tt>w+</tt> or <tt>w+b</tt> or <tt>wb+</tt></p></td><td class="docTableCell" align="left" valign="top"><p class="docText">truncate to 0 length or create for reading and writing</p></TD></tr><TR><td class="rightBorder" align="left" valign="top"><p class="docText"><tt>a+</tt> or <tt>a+b</tt> or <tt>ab+</tt></P></td><td class="docTableCell" align="left" valign="top"><p class="docText">open or create for reading and writing at end of file</p></td></tr></table></p><br>
<p class="docText">Using the character <tt>b</tt> as part of the <span class="docEmphasis">type</span> allows the standard I/O system to differentiate between a text file and a binary file. Since the UNIX kernel doesn't differentiate between these types of files, specifying the character <tt>b</tt> as part of the <span class="docEmphasis">type</span> has no effect.</p>
<p class="docText"><a name="idd1e36241"></a><a name="idd1e36244"></a><a name="idd1e36247"></a><a name="idd1e36252"></a><a name="idd1e36259"></a><a name="idd1e36264"></a><a name="idd1e36269"></a><a name="idd1e36274"></a><a name="idd1e36277"></a><a name="idd1e36282"></a><a name="idd1e36287"></a><a name="idd1e36292"></a><a name="idd1e36297"></a><a name="idd1e36300"></a><a name="idd1e36305"></a>With <tt>fdopen</tt>, the meanings of the <span class="docEmphasis">type</span> argument differ slightly. The descriptor has already been opened, so opening for write does not truncate the file. (If the descriptor was created by the <tt>open</tt> function, for example, and the file already existed, the <tt>O_TRUNC</tt> flag would control whether or not the file was truncated. The <tt>fdopen</tt> function cannot simply truncate any file it opens for writing.) Also, the standard I/O append mode cannot create the file (since the file has to exist if a descriptor refers to it).</p>
<p class="docText">When a file is opened with a type of append, each write will take place at the then current end of file. If multiple processes open the same file with the standard I/O append mode, the data from each process will be correctly written to the file.</p>
<blockquote>
<p class="docText">Versions of <tt>fopen</tt> from Berkeley before 4.4BSD and the simple version shown on page 177 of Kernighan and Ritchie [<a class="docLink" href="bib01.html#biblio01_003">1988</a>] do not handle the append mode correctly. These versions do an <tt>lseek</tt> to the end of file when the stream is opened. To correctly support the append mode when multiple processes are involved, the file must be opened with the <tt>O_APPEND</tt> flag, which we discussed in <a class="docLink" href="ch03lev1sec3.html#ch03lev1sec3">Section 3.3</a>. Doing an <tt>lseek</tt> before each write won't work either, as we discussed in <a class="docLink" href="ch03lev1sec11.html#ch03lev1sec11">Section 3.11</a>.</p>
</blockquote>
<p class="docText">When a file is opened for reading and writing (the plus sign in the <span class="docEmphasis">type</span>), the following restrictions apply.</p>
<ul><li><p class="docList">Output cannot be directly followed by input without an intervening <tt>fflush</tt>, <tt>fseek</tt>, <tt>fsetpos</tt>,or <tt>rewind</tt>.</p></li><li><p class="docList">Input cannot be directly followed by output without an intervening <tt>fseek</tt>, <tt>fsetpos</tt>,or <tt>rewind</tt>, or an input operation that encounters an end of file.</P></LI></ul>
<p class="docText">We can summarize the six ways to open a stream from <a class="docLink" href="#ch05fig02">Figure 5.2</a> in <a class="docLink" href="#ch05fig03">Figure 5.3</a>.</P>
<a name="ch05fig03"></a><P><table cellspacing="0" class="allBorders" border="1" RULES="groups" cellpadding="5"><caption><H5 class="docTableTitle">Figure 5.3. Six ways to open a standard I/O stream</h5></caption><colgroup><col width="260"><col width="40"><col width="40"><col width="40"><col width="40"><col width="40"><col width="40"></colgroup><thead><TR><th class="rightBorder bottomBorder thead" scope="col" align="center" valign="top"><p class="docText"><span class="docEmphRoman">Restriction</span></P></th><th class="rightBorder bottomBorder thead" scope="col" align="center" valign="top"><p class="docText"><span class="docEmphRoman"><tt>r</tt></span></P></th><th class="rightBorder bottomBorder thead" scope="col" align="center" valign="top"><p class="docText"><span class="docEmphRoman"><tt>w</tt></span></p></th><th class="rightBorder bottomBorder thead" scope="col" align="center" valign="top"><p class="docText"><span class="docEmphRoman"><tt>a</tt></span></P></th><th class="rightBorder bottomBorder thead" scope="col" align="center" valign="top"><p class="docText"><span class="docEmphRoman"><tt>r+</tt></span></p></th><th class="rightBorder bottomBorder thead" scope="col" align="center" valign="top"><p class="docText"><span class="docEmphRoman"><tt>w+</tt></span></P></th><th class="bottomBorder thead" scope="col" align="center" valign="top"><p class="docText"><span class="docEmphRoman"><tt>a+</tt></span></P></th></TR></thead><tr><TD class="rightBorder" align="left" valign="top"><p class="docText">file must already exist</P></td><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><td class="rightBorder" align="left" valign="top">&nbsp;</td><td class="rightBorder" align="left" valign="top">&nbsp;</TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="rightBorder" align="left" valign="top">&nbsp;</td><td class="docTableCell" align="left" valign="top">&nbsp;</td></tr><tr><td class="rightBorder bottomBorder" align="left" valign="top"><p class="docText">previous contents of file discarded</p></td><td class="rightBorder bottomBorder" align="left" valign="top">&nbsp;</td><td class="rightBorder bottomBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="rightBorder bottomBorder" align="left" valign="top">&nbsp;</td><td class="rightBorder bottomBorder" align="left" valign="top">&nbsp;</td><TD class="rightBorder bottomBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="bottomBorder" align="left" valign="top">&nbsp;</TD></TR><tr><TD class="rightBorder" align="left" valign="top"><p class="docText">stream can be read</P></TD><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="rightBorder" align="left" valign="top">&nbsp;</TD><TD class="rightBorder" align="left" valign="top">&nbsp;</td><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</P></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td></TR><tr><TD class="rightBorder" align="left" valign="top"><p class="docText">stream can be written</p></TD><td class="rightBorder" align="left" valign="top">&nbsp;</td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></td><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</p></td></TR><TR><td class="rightBorder" align="left" valign="top"><p class="docText">stream can be written only at end</P></TD><TD class="rightBorder" align="left" valign="top">&nbsp;</td><TD class="rightBorder" align="left" valign="top">&nbsp;</TD><TD class="rightBorder" align="center" valign="top"><p class="docText">&#8226;</p></TD><td class="rightBorder" align="left" valign="top">&nbsp;</TD><TD class="rightBorder" align="left" valign="top">&nbsp;</TD><td class="docTableCell" align="center" valign="top"><p class="docText">&#8226;</P></TD></tr></table></P><BR>
<p class="docText">Note that if a new file is created by specifying a <span class="docEmphasis">type</span> of either <tt>w</tt> or <tt>a</tt>, we are not able to specify the file's access permission bits, as we were able to do with the <tt>open</tt> function and the <tt>creat</tt> function in <a class="docLink" href="ch03.html#ch03">Chapter 3</a>.</p>
<p class="docText">By default, the stream that is opened is fully buffered, unless it refers to a terminal device, in which case it is line buffered. Once the stream is opened, but before we do any other operation on the stream, we can change the buffering if we want to, with the <tt>setbuf</tt> or <tt>setvbuf</tt> functions from the previous section.</p>
<p class="docText">An open stream is closed by calling <tt>fclose</tt>.</p>
<a name="inta50"></a><p><table cellspacing="0" class="allBorders" border="1" RULES="none" cellpadding="5"><colgroup><col width="500"></colgroup><thead></thead><TR><td class="docTableCell" align="left" valign="top"><p class="docText">
<pre>
#include &lt;stdio.h&gt;

int fclose(FILE *<span class="docEmphItalicAlt">fp</span>);
</pre><BR>

</p></TD></tr><tr><td class="docTableCell" align="right" valign="top"><p class="docText">Returns: 0 if OK, <tt>EOF</tt> on error</p></td></tr></table></p><br>
<p class="docText"><a name="idd1e36682"></a><a name="idd1e36687"></a><a name="idd1e36692"></a><a name="idd1e36699"></a><a name="idd1e36704"></a><a name="idd1e36709"></a><a name="idd1e36714"></a><a name="idd1e36719"></a><a name="idd1e36724"></a><a name="idd1e36731"></a><a name="idd1e36736"></a><a name="idd1e36743"></a><a name="idd1e36748"></a><a name="idd1e36753"></a>Any buffered output data is flushed before the file is closed. Any input data that may be buffered is discarded. If the standard I/O library had automatically allocated a buffer for the stream, that buffer is released.</p>
<p class="docText">When a process terminates normally, either by calling the <tt>exit</tt> function directly or by returning from the <tt>main</tt> function, all standard I/O streams with unwritten buffered data are flushed, and all open standard I/O streams are closed.</p>

<a href="17021535.html"><img src="images/pixel.gif" alt="" width="1" height="1" border="0"></a><ul></ul></td></tr></table>
<table width="100%" border="0" cellspacing="0" cellpadding="0">
<tr><td><div STYLE="MARGIN-LEFT: 0.15in;"><a href="toc.html"><img src="images/team.gif" width="60" height="17" border="0" align="absmiddle"  alt="Team BBL"></a></div></td>
<td align="right"><div STYLE="MARGIN-LEFT: 0.15in;">
<a href=ch05lev1sec4.html><img src="images/prev.gif" width="60" height="17" border="0" align="absmiddle" alt="Previous Page"></a>
<a href=ch05lev1sec6.html><img src="images/next.gif" width="60" height="17" border="0" align="absmiddle" alt="Next Page"></a>
</div></td></tr></table>
</body></html><br>
<table width="100%" cellspacing="0" cellpadding="0"
style="margin-top: 0pt; border-collapse: collapse;"> 
<tr> <td align="right" style="background-color=white; border-top: 1px solid gray;"> 
<a href="http://www.zipghost.com/" target="_blank" style="font-family: Tahoma, Verdana;
 font-size: 11px; text-decoration: none;">The CHM file was converted to HTM by Trial version of <b>ChmD<!--72-->ecompiler</b>.</a>
</TD>
</TR><tr>
<td align="right" style="background-color=white; "> 
<a href="http://www.etextwizard.com/download/cd/cdsetup.exe" target="_blank" style="font-family: Tahoma, Verdana;
 font-size: 11px; text-decoration: none;">Download <b>ChmDec<!--72-->ompiler</b> at: http://www.zipghost.com</a>
</TD></tr></table>
